Using Callable IDL

The process of using Callable IDL has three stages: initialization, IDL use, and cleanup.

Between the initialization and the cleanup, your program contains a complete active IDL session just as if a user were typing commands at an IDL> prompt. In addition to the usual IDL abilities, you can import data from your program and cause IDL to see it as an IDL variable. IDL can use such data in computations as if it had created the variable itself. In addition, you can obtain pointers to data currently held by IDL variables and access the results of IDL computations from your program.

Note: The functions documented in this chapter should only be used when calling IDL from other programs—their use in code called by IDL via CALL_EXTERNAL or a system routine (LINKIMAGE, Dynamically Loadable Module) is not supported and is certain to corrupt and/or crash the IDL process.

Before calling IDL to execute instructions, you must initialize it. This is done by calling IDL_Initialize(). This is a one-time operation, and must occur before calling any other IDL function. Once IDL is initialized, you can:

1. Send IDL commands to IDL for execution. Commands are sent as strings, using the same syntax as interactive IDL. Note that there is not a separate C language function for every IDL command—any valid IDL command can be executed as IDL statements. This approach allows us to keep the callable IDL API small and simple while allowing full access to IDL’s abilities. This is explained in Executing IDL Statements.
2. Call any of the several routines that interact with IDL through other means to perform operations such as:
   • Importing data into IDL. (See Creating an Array from Existing Data.)
   • Accessing data within IDL. (See Looking Up Variables in Current Scope".)
   • Changing items in the process, such as signal handling or timers. (See “IDL Internals: UNIX Signals, or IDL Internals: Timers".)
   • Redirecting IDL output to your own function for processing. See “Diverting IDL Output.

The above list is not complete, but is representative of the possibilities afforded by Callable IDL.

Cleanup

After all IDL use is complete, but before the program exits, you must call IDL_Cleanup() to allow IDL to shutdown gracefully and clean up after itself. Once this has been done, you are not allowed to call IDL again from this process. See Cleanup for more information.